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/Audit/ApiAuditLogRepository.php

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\Audit;
 use MintyPHP\DB;
 use MintyPHP\Repository\Support\RepoQuery;
 
+/** Records API request/response audit entries with status codes, timing, and error details. */
 class ApiAuditLogRepository implements ApiAuditLogRepositoryInterface
 {
     private const FILTER_OPTIONS_LIMIT_MAX = 200;

lib/Repository/Audit/ApiAuditLogRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Audit;
 
+/** Contract for API request audit log creation, pagination, and retention purge. */
 interface ApiAuditLogRepositoryInterface
 {
     public function create(array $data): int|false;

lib/Repository/Audit/ImportAuditRunRepository.php

@@ -6,6 +6,7 @@ use MintyPHP\DB;
 use MintyPHP\Domain\Taxonomy\ImportAuditStatus;
 use MintyPHP\Repository\Support\RepoQuery;
 
+/** Tracks CSV import runs including source file, row counts, status, and completion metadata. */
 class ImportAuditRunRepository implements ImportAuditRunRepositoryInterface
 {
     private const FILTER_OPTIONS_LIMIT_MAX = 200;

lib/Repository/Audit/ImportAuditRunRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Audit;
 
+/** Contract for CSV import run audit trail creation, completion, and purge. */
 interface ImportAuditRunRepositoryInterface
 {
     public function createRunning(array $data): int|false;

lib/Repository/Audit/SystemAuditLogRepository.php

@@ -7,6 +7,7 @@ use MintyPHP\Domain\Taxonomy\SystemAuditChannel;
 use MintyPHP\Domain\Taxonomy\SystemAuditOutcome;
 use MintyPHP\Repository\Support\RepoQuery;
 
+/** Persists system audit events with actor, target, outcome, channel, and hashed request metadata. */
 class SystemAuditLogRepository implements SystemAuditLogRepositoryInterface
 {
     private const FILTER_OPTIONS_LIMIT_MAX = 200;

lib/Repository/Audit/SystemAuditLogRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Audit;
 
+/** Contract for system-wide security event logging with channel and outcome filtering. */
 interface SystemAuditLogRepositoryInterface
 {
     public function create(array $data): int|false;

lib/Repository/Audit/UserLifecycleAuditRepository.php

@@ -8,6 +8,7 @@ use MintyPHP\Domain\Taxonomy\UserLifecycleStatus;
 use MintyPHP\Domain\Taxonomy\UserLifecycleTriggerType;
 use MintyPHP\Repository\Support\RepoQuery;
 
+/** Records user lifecycle transitions (deactivation, deletion, restore) with reason codes and snapshots. */
 class UserLifecycleAuditRepository implements UserLifecycleAuditRepositoryInterface
 {
     private const FILTER_OPTIONS_LIMIT_MAX = 200;

lib/Repository/Audit/UserLifecycleAuditRepositoryInterface.php

@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Repository\Audit;
 
+/** Contract for tracking user deactivation/deletion lifecycle events and restore eligibility. */
 interface UserLifecycleAuditRepositoryInterface
 {
     public function create(array $row): int|false;