docs: enhance test file comments for clarity on upgrade test setup and validation

Author: SatabdiG

test/upgrade/main_test.go

@@ -1,5 +1,17 @@
 //go:build upgrade
 
+//
+// This file (main_test.go) contains TestMain and cluster setup logic for all upgrade tests.
+// It performs the following initialization:
+//   - Creates a kind cluster with Crossplane and the CloudFoundry provider
+//   - Configures the provider with DeploymentRuntimeConfig for debug logging
+//   - Handles both "local" (development) and registry (release) provider images
+//   - Sets up CloudFoundry credentials as a Kubernetes secret
+//   - Discovers and loads test resources from testdata directories
+//
+// The setup happens once before all tests run, ensuring consistent test environment
+// across both baseline and custom upgrade tests.
+
 package upgrade
 
 import (

test/upgrade/space_external_name_upgrade_test.go

@@ -1,5 +1,15 @@
 //go:build upgrade
 
+//
+// This file (space_external_name_upgrade_test.go) contains Test_Space_External_Name,
+// which validates that Space resources maintain proper external-name formatting
+// during provider upgrades. Specifically, it verifies:
+//   - External-name annotation exists and follows UUID format
+//   - External-name value remains unchanged after provider upgrade
+//
+// This test demonstrates the use of CustomUpgradeTestBuilder for creating
+// specialized upgrade tests with custom pre/post-upgrade validation logic.
+
 package upgrade
 
 import (