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/Support/DatabaseSessionRepository.php

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Support;
 
 use MintyPHP\DB;
 
+/** Executes database session operations: advisory locks, transactions, and commit/rollback. */
 class DatabaseSessionRepository implements DatabaseSessionRepositoryInterface
 {
     public function acquireAdvisoryLock(string $lockName, int $timeoutSeconds = 0): bool
@@ -47,4 +48,33 @@ class DatabaseSessionRepository implements DatabaseSessionRepositoryInterface
     {
         DB::handle()->rollback();
     }
+
+    /**
+     * Run a callback inside a DB transaction. Commits on success, rolls back on exception.
+     *
+     * Eliminates the need for manual begin/commit/rollback + rollbackQuietly() boilerplate
+     * that is duplicated across multiple services. The callback receives no arguments;
+     * use closures to capture dependencies.
+     *
+     * @template T
+     * @param callable(): T $callback
+     * @return T The value returned by the callback.
+     * @throws \Throwable Re-throws the original exception after rollback.
+     */
+    public function transaction(callable $callback): mixed
+    {
+        $this->beginTransaction();
+        try {
+            $result = $callback();
+            $this->commitTransaction();
+            return $result;
+        } catch (\Throwable $e) {
+            try {
+                $this->rollbackTransaction();
+            } catch (\Throwable) {
+                // Swallow — the original exception is more important.
+            }
+            throw $e;
+        }
+    }
 }