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/User/UserExternalIdentityRepository.php

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\User;
 
 use MintyPHP\DB;
 
+/** Links and looks up external identity provider accounts (Entra ID / OIDC) for users. */
 class UserExternalIdentityRepository implements UserExternalIdentityRepositoryInterface
 {
     private function unwrap($row): ?array

lib/Repository/User/UserExternalIdentityRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\User;
 
+/** Contract for linking external identity provider accounts (OIDC) to users. */
 interface UserExternalIdentityRepositoryInterface
 {
     public function findByProviderTidOid(string $provider, string $tid, string $oid): ?array;

lib/Repository/User/UserListQueryRepository.php

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\User;
 use MintyPHP\DB;
 use MintyPHP\Repository\Support\RepoQuery;
 
+/** Builds and executes complex user list queries with search, date, role, department, and custom field filters. */
 class UserListQueryRepository implements UserListQueryRepositoryInterface
 {
     private function buildUserFilters(array $options): array

lib/Repository/User/UserListQueryRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\User;
 
+/** Contract for paginated user listing with multi-criteria filtering. */
 interface UserListQueryRepositoryInterface
 {
     public function listPaged(array $options): array;

lib/Repository/User/UserReadRepository.php

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\User;
 
 use MintyPHP\DB;
 
+/** Retrieves user records and authorization snapshots; no write operations. */
 class UserReadRepository implements UserReadRepositoryInterface
 {
     public function findAuthzSnapshot(int $userId): ?array

lib/Repository/User/UserReadRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\User;
 
+/** Contract for read-only user lookups by ID, UUID, email, and authorization snapshots. */
 interface UserReadRepositoryInterface
 {
     public function findAuthzSnapshot(int $userId): ?array;

lib/Repository/User/UserSavedFilterRepository.php

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\User;
 use MintyPHP\DB;
 use MintyPHP\Repository\Support\RepoQuery;
 
+/** Persists and retrieves user-defined search filter presets per list context. */
 class UserSavedFilterRepository implements UserSavedFilterRepositoryInterface
 {
     private function unwrapList($rows): array

lib/Repository/User/UserSavedFilterRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\User;
 
+/** Contract for per-user, per-context persistence of saved search filters. */
 interface UserSavedFilterRepositoryInterface
 {
     public function listByUserAndContext(int $userId, string $context): array;

lib/Repository/User/UserWriteRepository.php

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\User;
 use MintyPHP\DB;
 use MintyPHP\Repository\Support\RepoQuery;
 
+/** Creates and mutates user records including activation, tenant links, and preferences. */
 class UserWriteRepository implements UserWriteRepositoryInterface
 {
     public function updateLastLogin(int $userId, string $provider = 'local'): void

lib/Repository/User/UserWriteRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\User;
 
+/** Contract for user creation, updates, activation, tenant assignment, and preference changes. */
 interface UserWriteRepositoryInterface
 {
     public function updateLastLogin(int $userId, string $provider = 'local'): void;