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/Services/AgentSettlement/AgentSettlementPeriodPipelineService.php

@@ -3,7 +3,7 @@
 namespace App\Services\AgentSettlement;
 
 use App\Models\AdminUser;
-use App\Support\AdminDataScope;
+use App\Support\AdminAgentSettlementScope;
 use App\Support\AgentSettlementPeriodWindow;
 use App\Support\PlayerFundingMode;
 use Illuminate\Support\Collection;
@@ -71,17 +71,18 @@ final class AgentSettlementPeriodPipelineService
                 ->whereBetween('cl.created_at', [$start, $end]);
 
             if ($admin !== null) {
-                AdminDataScope::applyToPlayersAlias($creditQuery, $admin, 'p');
+                AdminAgentSettlementScope::applyDirectPlayersToAlias($creditQuery, $admin, 'p');
             }
 
             $shareQuery = DB::table('share_ledger as sl')
                 ->join('players as p', 'p.id', '=', 'sl.player_id')
                 ->where('p.site_code', $siteCode)
+                ->whereNull('sl.settlement_period_id')
                 ->whereBetween('sl.settled_at', [$start, $end])
                 ->whereNull('sl.reversal_of_id');
 
             if ($admin !== null) {
-                AdminDataScope::applyToPlayersAlias($shareQuery, $admin, 'p');
+                AdminAgentSettlementScope::applyDirectPlayersToAlias($shareQuery, $admin, 'p');
             }
 
             $shareAgg = (clone $shareQuery)