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

@@ -8,6 +8,18 @@ use MintyPHP\Repository\Access\RolePermissionRepositoryInterface;
 use MintyPHP\Repository\Access\UserRoleRepositoryInterface;
 use MintyPHP\Service\Audit\SystemAuditService;
 
+/**
+ * Central RBAC permission service — resolves and caches permission keys for users.
+ *
+ * Permission resolution: User → Roles (via user_roles) → Permissions (via role_permissions).
+ * The resolved key list is cached in two tiers:
+ *   - API requests (stateless): in-memory array, lives for one request cycle.
+ *   - Web requests: session store, survives across page loads until refresh.
+ * A forced refresh can be triggered by passing $refresh = true to getUserPermissions().
+ *
+ * All permission key constants are defined here as the single source of truth,
+ * referenced by actions, services, policies, and templates.
+ */
 class PermissionService
 {
     private array $apiPermissionCache = [];