docs: add class docblocks, business-rule comments, and transaction wrapper

- Add single-line class docblocks to all 59 repository classes and interfaces
  describing scope and responsibility
- Add multi-line docblocks to key services documenting business rules:
  AuthService (6-step login cascade), ImportService (3-phase CSV workflow),
  TenantScopeService (strict/permissive modes), PermissionService (RBAC
  resolution + two-tier caching), UserAccountService (atomicity + audit)
- Add transaction(callable) wrapper to DatabaseSessionRepository to DRY up
  begin/commit/rollback boilerplate

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

lib/Repository/Auth/ApiTokenRepository.php

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\Auth;
 use MintyPHP\DB;
 use MintyPHP\Repository\Support\RepoQuery;
 
+/** Persists API tokens with selector/hash pairs, expiry tracking, and usage timestamps. */
 class ApiTokenRepository implements ApiTokenRepositoryInterface
 {
     private const UUID_REGEX = '/^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i';

lib/Repository/Auth/ApiTokenRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Auth;
 
+/** Contract for API bearer token creation, lookup by selector or UUID, and revocation. */
 interface ApiTokenRepositoryInterface
 {
     public function isUuid(string $value): bool;

lib/Repository/Auth/EmailVerificationRepository.php

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Auth;
 
 use MintyPHP\DB;
 
+/** Stores email verification codes with attempt counters, expiry, and completion status. */
 class EmailVerificationRepository implements EmailVerificationRepositoryInterface
 {
     public function create(int $userId, string $codeHash, string $expiresAt): ?int

lib/Repository/Auth/EmailVerificationRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Auth;
 
+/** Contract for email verification code lifecycle: creation, lookup, attempt tracking, and completion. */
 interface EmailVerificationRepositoryInterface
 {
     public function create(int $userId, string $codeHash, string $expiresAt): ?int;

lib/Repository/Auth/PasswordResetRepository.php

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Auth;
 
 use MintyPHP\DB;
 
+/** Stores password reset codes with attempt counters, expiry, and completion history. */
 class PasswordResetRepository implements PasswordResetRepositoryInterface
 {
     private function unwrapList($rows): array

lib/Repository/Auth/PasswordResetRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Auth;
 
+/** Contract for password reset code lifecycle: creation, lookup, attempt tracking, and completion. */
 interface PasswordResetRepositoryInterface
 {
     public function create(int $userId, string $codeHash, string $expiresAt): ?int;

lib/Repository/Auth/RememberTokenRepository.php

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Auth;
 
 use MintyPHP\DB;
 
+/** Manages persistent login tokens with rotation, family tracking, and admin-initiated expiry. */
 class RememberTokenRepository implements RememberTokenRepositoryInterface
 {
     private function unwrapList($rows): array

lib/Repository/Auth/RememberTokenRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Auth;
 
+/** Contract for remember-me token creation, rotation, expiry, and active session counting. */
 interface RememberTokenRepositoryInterface
 {
     public function create(int $userId, string $selector, string $tokenHash, string $expiresAt): ?int;