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/Service/Auth/AuthService.php

@@ -14,6 +14,21 @@ use MintyPHP\Service\User\UserTenantContextService;
 use MintyPHP\Session;
 use MintyPHP\Support\Flash;
 
+/**
+ * Orchestrates authentication flows: login, registration, logout, and session refresh.
+ *
+ * Login is a cascading validation — each step must pass before the next is attempted:
+ *   1. Email verification status (unverified → redirect to verification)
+ *   2. Credential check via Auth::login (email + password)
+ *   3. Account active flag
+ *   4. Local password login allowed (at least one tenant permits it)
+ *   5. Permissions loaded + tenant context hydrated into session
+ *   6. At least one active tenant assigned
+ *
+ * Every outcome (success or failure at any step) is recorded as an audit event.
+ * On SSO-initiated login (loginUserById), steps 1-4 are skipped because the IdP
+ * already authenticated the user; steps 5-6 still apply.
+ */
 class AuthService
 {
     public function __construct(
@@ -293,6 +308,14 @@ class AuthService
         $this->systemAuditService->record($eventType, $outcome, $context);
     }
 
+    /**
+     * Re-validates the session against the current DB state.
+     *
+     * Uses an authz_version counter: the DB version is bumped whenever permissions or
+     * tenant assignments change. A mismatch with the session version triggers a full
+     * reload of user data, permissions, and tenant context. This is the mechanism that
+     * makes permission changes take effect without requiring re-login.
+     */
     public function refreshSessionAuthState(int $userId): array
     {
         if ($userId <= 0) {