docs: clarify google_sql_database_instance edition default (PG16 -> ENTERPRISE_PLUS) and tier compatibility

Author: pete-csyn

mmv1/third_party/terraform/website/docs/r/sql_database_instance.html.markdown

@@ -431,9 +431,16 @@ The `settings` block supports:
 
 * `tier` - (Required) The machine type to use. See [tiers](https://cloud.google.com/sql/docs/admin-api/v1beta4/tiers)
     for more details and supported versions. Postgres supports only shared-core machine types,
-    and custom machine types such as `db-custom-2-13312`. See the [Custom Machine Type Documentation](https://cloud.google.com/compute/docs/instances/creating-instance-with-custom-machine-type#create) to learn about specifying custom machine types.
-
-* `edition` - (Optional) The edition of the instance, can be `ENTERPRISE` or `ENTERPRISE_PLUS`.
+    and custom machine types such as `db-custom-2-13312`. See the [Custom Machine Type Documentation](https://cloud.google.com/compute/docs/instances/creating-instance-with-custom-machine-type#create) to learn about specifying custom machine types. Note that shared-core and custom machine types are valid only under the `ENTERPRISE` edition; PostgreSQL 16+ instances default to `ENTERPRISE_PLUS` when `edition` is unset (see the `edition` argument below).
+
+* `edition` - (Optional) The edition of the instance, can be `ENTERPRISE` or `ENTERPRISE_PLUS`. If `edition`
+    is not set, the Cloud SQL API determines the default based on `database_version`: instances with
+    `database_version` `POSTGRES_16` or later default to `ENTERPRISE_PLUS`, while all others default to
+    `ENTERPRISE`. Note that `ENTERPRISE_PLUS` supports only predefined `db-perf-optimized-N-*` machine
+    types (the `N2`/`C4A` series); shared-core and custom tiers such as `db-g1-small`, `db-f1-micro`, and
+    `db-custom-*` require `edition = "ENTERPRISE"`. Omitting `edition` on a PostgreSQL 16+ instance while
+    setting a shared-core or custom `tier` therefore fails at create time with
+    `Invalid Tier (...) for (ENTERPRISE_PLUS) Edition`.
 
 * `user_labels` - (Optional) A set of key/value user label pairs to assign to the instance.