feat: enhance agent settlement features and improve data access controls

- Added new section in AGENTS.md detailing learned workspace facts for better understanding of settlement processes.
- Updated AgentNodeDestroyController to remove unnecessary checks for admin users.
- Enhanced AgentSettlement controllers to assert permissions for finance adjustments and bill operations.
- Improved query scopes in AgentSettlement services to ensure proper data access based on admin roles.
- Refactored methods in SettlementPartyEnrichment for better bill row enrichment and data handling.
- Introduced new methods in AdminAgentSettlementScope for managing agent node visibility and finance adjustments.

app/Http/Controllers/Api/V1/Admin/AgentSettlement/AgentSettlementReportShowController.php

@@ -4,6 +4,7 @@ namespace App\Http\Controllers\Api\V1\Admin\AgentSettlement;
 
 use App\Http\Controllers\Controller;
 use App\Services\AgentSettlement\AgentSettlementReportQueryService;
+use App\Support\AdminAgentScope;
 use App\Support\AgentSettlementPeriodWindow;
 use App\Support\ApiResponse;
 use Illuminate\Http\JsonResponse;
@@ -31,6 +32,10 @@ final class AgentSettlementReportShowController extends Controller
         $type = (string) $request->query('type', 'summary');
         abort_unless(in_array($type, self::TYPES, true), 404);
 
+        if ($type === 'platform_pnl' && AdminAgentScope::primaryAgentNode($admin) !== null) {
+            abort(403, 'agent_cannot_view_platform_pnl');
+        }
+
         $periodId = (int) $request->query('settlement_period_id', 0);
         $period = $this->resolvePeriod($periodId, $request);