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/Access/PermissionRepository.php

@@ -6,6 +6,7 @@ use MintyPHP\DB;
 use MintyPHP\Repository\Support\RepoQuery;
 use MintyPHP\Repository\Support\RepositoryArrayHelper;
 
+/** Reads and writes permission records; supports active/system flag filtering. */
 class PermissionRepository implements PermissionRepositoryInterface
 {
     public function list(): array

lib/Repository/Access/PermissionRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Access;
 
+/** Contract for permission CRUD and lookup by key or ID. */
 interface PermissionRepositoryInterface
 {
     public function list(): array;

lib/Repository/Access/RoleAssignableRoleRepository.php

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Access;
 
 use MintyPHP\DB;
 
+/** Manages which roles a given role is allowed to assign (role hierarchy). */
 class RoleAssignableRoleRepository implements RoleAssignableRoleRepositoryInterface
 {
     public function listAssignableRoleIdsByRoleId(int $roleId): array

lib/Repository/Access/RolePermissionRepository.php

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Access;
 
 use MintyPHP\DB;
 
+/** Manages the many-to-many link between roles and permissions. */
 class RolePermissionRepository implements RolePermissionRepositoryInterface
 {
     public function listPermissionIdsByRoleId(int $roleId): array

lib/Repository/Access/RolePermissionRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Access;
 
+/** Contract for managing permission assignments on roles. */
 interface RolePermissionRepositoryInterface
 {
     public function listPermissionIdsByRoleId(int $roleId): array;

lib/Repository/Access/RoleRepository.php

@@ -6,6 +6,7 @@ use MintyPHP\DB;
 use MintyPHP\Repository\Support\RepoQuery;
 use MintyPHP\Repository\Support\RepositoryArrayHelper;
 
+/** Reads and writes role records with pagination, search, and code uniqueness checks. */
 class RoleRepository implements RoleRepositoryInterface
 {
     public function list(): array

lib/Repository/Access/RoleRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Access;
 
+/** Contract for role CRUD, existence checks, and filtered listing. */
 interface RoleRepositoryInterface
 {
     public function list(): array;

lib/Repository/Access/UserRoleRepository.php

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\Access;
 use MintyPHP\DB;
 use MintyPHP\Repository\Support\RepositoryArrayHelper;
 
+/** Queries user-role assignments and counts active/inactive users per role. */
 class UserRoleRepository implements UserRoleRepositoryInterface
 {
     public function listRoleIdsByUserId(int $userId): array

lib/Repository/Access/UserRoleRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Access;
 
+/** Contract for querying user-role relationships and role usage counts. */
 interface UserRoleRepositoryInterface
 {
     public function listRoleIdsByUserId(int $userId): array;